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RJ’s WorkBench Specifiction, rough pass dated 5 March 1984 (sic). I 
to provide a set of calls that provide the functionality specified in that document, but 
the calls have been repackaged to make the interface easier to implement. I also tried to 
the interface at a deeper level, listing the arguments and return values of the various calls. 

There are some issues in RJ’s original document that are not directly implementable or have not 
yet been worked out, and need to be done before Supposition can be written. Those issues appear 
after the interface specification. 


I am calling the interface between WorkBench and the DOS “Supposition”. Supposition is divided 
into two parts: those things that WorkBench will call to give it the information that it requires 
(such as opening an object) and those things that Supposition will inform WorkBench about. 


2. Definitions 


2.1. Supposition 

Supposition is the interface between WorkBench and the Disk based operating system (DOS). 

2.2. Path Name 

For this document a file name is a pair of two values: a Tripos lock and a path description rela¬ 
tive to that lock. Throughout this document then the term PathName ( or just path for short) it 
refers to one of these pairs. Absolute pathnames can be refered to by using a null lock and fully 
specifying the path name. 


2.3. Disks, Drawers, Objects, and Directories 

An Object corresponds to a WorkBench displayable entity. Objects may be disks, tools, projects, 
or drawers. 

A Drawer is a WorkBench object that contains other WorkBench objects. A Drawer may not also 
be a tool or a project. Several operations (such as OpenDrawer) only make sense when applied to 
drawers. 


Tools and projects are implemented via DOS directories, as are drawers. The difference is that 
tools and projects are “leaf nodes” in the WorkBench representation, both projects and tools may 
contain subdirectories, but these subdirectories are normally invisible to WorkBench. 



disk is~~eitlTer inserted or removed. Workbench also knows if anything is active on the disk, so it 
can tell if it should keep the disk around.A A disk is active (iconically displayed) when either the 
disk is in the drive, or when something on the disk is active. 


Currently I sometimes draw a distinction between specific types of objects (disks, drawers), and 
generic objects in some of the calls. This is mostly for convenience in specifing what sort of 
objects it makes sense to pass to that routine; I hope that I can use the same data structure to 
represent all objects. 


3. WorkBench to Supposition Interface 

This section refers to the direct requests that can be made to Supposition. 

3.1. RunToolQ 

struct RunningTool * 

RunTool( ToolPath, argcount, arglist ) 
struct Path *ToolPath; 
int argcount; 
struct Path *arglist[]; 
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RunTool starts a tool up and running. It takes a (possibly null) list of projects and/or arguments 
to pass on to the tool. It returns a handle on the tool that can be used to communicate with the 
tool. In addition this handle is used to detect when the tool has terminated. If the call did not 
succeed, then a NULL will be returned. 


3.2. StopToolQ 

StopTool( Tool ) 
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StopTool attempts to close an active instance of a tool (e.g. a tool started by RunTool). It will 
probably use a signal to inform the tool that it should clean up and go away. The tool is allowed 
to defer or ignore a request to close itself, or query the user-tp-see if he realy wanted to close this 
tool. WorkBench will be informed of the actual close via DeadTool. 

3.3. OpenDrawer() ^-—--- 

OpenDrawer( Parent ) 
struct OpenObject *Parent; 

Abstractly, OpenDrawer does all the research required to open a new drawer on the screen. It 
reads all the entries in a parent drawer. It will fill in the odjOhild entry in the parent’s OpenOb¬ 
ject structure to point to the first child draweiyead in. Each child drawervwill in turn be linked 
together, and all these siblings will point back-at the parent drawer. Each^child^rawer on this 
list will have the required information obtained from the drawer descriptlopTfileTsuch as gadget 

type ' etc - ... v 

*** We need a list of this information *** 'Os' ~ 

^Unlike the WorkBench spec, this call will NOT recurse down the diredTory~ireeT^"™ 

w 

If there is an error during the directory search a NULL will be returned. 

There are some aspects of reading a directory that I don’t yet understand. This call may change 
some as I get the details that I need. 






3.4. CloseDrawerQ 

CloseDrawer( Object ) 
struct OpenObject ^Object; 
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This call frees the resources tied Jp by an OpenDrawer. It should be done when the drawer is ; 
closed or wh^rrWorklJench is exiting. ^____ 


If there are child drawers currently open for this drawer the children will be updated to know that 
their parent is gone . ___*_ __ _____ 

Tlie drawer will have^its usage count decremented. Any drawer that has a usage count of zero 
will have its memory freed. 



vO) 

JO 


^ 7 


3.5. OpenDisk() 

struct OpenObject * 

OpenDisk( Disk ) 
struct OpenDisk *Disk; 

OpenDisk returns a handle on the root drawer of the specified disk. This handle can in turn be 
used to read in the contents of that drawer. 

If the disk cannot be opened then a NULL is returned. 1 
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3.6. CloseDiskQ 

CloseDisk( Disk ) 
struct OpenDisk *Disk; 


The inverse operation of OpenDisk is CloseDisk. It should be called when the disk is inactive. A ~ 
disk should be niarked JLiiaaUve^when^lh-dTawersT-Tool^axid-.proiects from that disk have been 

closeaTWhis means that we will have to keep a usage count for itemTon that "disk.' f 
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3.7. Objectlnfo() 

SetObjectInfo( Object, Info ) 
GetObjectInfo( Object, Info ) 
struct OpenObject ♦Object; 
struct Objectlnfo *Info; 




Conventionally there is a set of information that is kept about an object. While we do not know 
the complete set of this information, it includes a description of its gadget, its type (tool, project, 
drawer, etc), some description description text, and information that is specific to the object type. 
In addition this filehmayjprovide handles to implement WorkBench operations, such as copying or 
removing the object. 

GetObjectlnfo obtains this information from the disk. SetObjectlnfo writes the information back 
out to disk. 


3.8. Object Manipulation 


MoveObject( Object, NewPath ) 
CopyObject( Object, NewPath ) 
Struct OpenObject ^Object; 
Struct PathName *NewPath; 
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These calls manipulate objects on the disk. The implementation will be object dependent, and 
may be implemented by the object itself (instead of by Supposition). )/ / 
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4. Supposition to WorkBench Interface 

These calls are the ones that supposition will call into WorkBench. 

4.1. Disk Changes 

Disklnserted( Disk ) 

DiskRemoved( Disk ) 
struct OpenDisk *Disk; 


CL. / Wr^- 





These WorkBench entry points will be called \vhenever a disk is inserted or removed. They are 
passes an identifier for the disk that is inserted. 


4.2. Object Changes 

ObjectChanged( Object ) 
struct OpenObject ♦Object; 

ObjectChanged is called when there the status of an object has been detected. This change may 
or may not actually require any WorkBench display changes; instead it says that changes could be 
required. The WorkBench data strucures are not actually maniputed; instead it is just marked as 
needing attention. 

If we can develop a locking mechanism for the object data structures then this call will not be 
needed; instead the objects may be updated directly and some sort of WorkBench refresh routine 
called if and only if there is a display able change. 
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4.3. DeadToolQ 

DeadTool( Tool ) , CLSaX 1 V-J4<P if crv'^y^s *r 

struct RunningTool *Tool; \J \^/ / J 

DtadTool informs WorkBench that a previously started tool has terminated. 

5. Open Issues \ ^ 

5.1. Memory A^o^ 

We will needJot^Sjf j^yrmmic data to implement WorkBenc) 

cleans it upVand^when it gets cleaned up are all open issues. 

\ \ 

I tried to outline some ideas of when things should be freed in some of the calls. 


ere we get this data from, who 


'5.2. Control Flow 

; We will need to structure the program so that both WorkBench and Supposition 
respective input. 'WorkBench needs to recieve input events from intuition; Supposition needs to 
recieve notifiction from the DOS, a timer, and processes that have terminated. In addition some 
events will happen asynchronously; the kindest description I can find for how Tripos deals with 
asynchrous events is “obsure”. 

I spoke with Tim King and we decided that the method that makes the most sense is to structure*] 
WorkBench the same as Tripos utilities that need to be asynchronous: they are structured as 
coroutines. This implies some methods on how Supposition and WorkBench should work. I am 


Ion can get tneir ^ f) 
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currently working on the low level assembly code to give C programs access to BCPL style corou 


tines. 


.A 5 .3.—Shared Data Structures 
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There will be many shared data objects between Supposition and WorkBench. We will^lieecfno 
develop a locking protocol so that the se ob jects are always consistent. / /a) 

DOS information 

Currently plans have the DOS keeping information on whether an object with a lock has been 
changed. Supposition can poll this information periodically to see if any of the objects that it 
cares about have changed. I believe that will will allow us to naturally check to see if a folder has 
had new items installed in it or removed. 

A more difficult problem is tracking the open status of projects. It has been suggested that Work- 
Bench should reflect the current state of objects; if a project is opened via a non-WorkBench path 
then the icon should reflect this. One problem is that there is currently no way that I know of to 
do this. Another is that icons will be flickering* on and off without the user interacting with Work-*, 

Bench - this will be confusing. Finally we don’t have a DOS level definition of what it means to f^UOKU 
“open a project”. We know how to pass a project on to a tool; however what that tool does with 
that project is completely up to it. What if the tool starts accessing another project? WorkBench 
has no knowledge of the semantics of the interactions between tools and projects. 

One compromise that would be simple to implement is to allow a tool to change the state of a 
project. We could provide a call to manipulate projects through their three states (closed, 
currently being read, or currently being written). 

5.5. Process relationships 1 
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To be filled in 
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5.6. Locating and Naming Tools 
To be filled in 


5.7. Rodent Removal 


Many people have a large resistance to mice and feel that they are not a convenient way to 
specify objects. We previously decided that we wanted to have an additional method of specify¬ 
ing objects and actions on them. This alternate method would still be graphical in nature: objects 
would highlight, move, and open the way they do with a mouse. However the method of specifing 
objects would be different: via function keys or by typing in names and control sequences. 

I think that there is a natural way for this to happen. However, this way would require Work- 
Bench to be sigificantly restructured. We need to think about how important this is and whether 
we can do it later. 
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